/*
================================================================================
File name: tinyduino_ledboard.h
   System: TinyDuino LED Shield Library
 Platform: TinyDuino (Amtel ATmega328, 3.3v, 8MHz)
   Author: Madeline Usher
  Created: July 11, 2013
  Purpose: The TinyDuino LED shield from TinyCircuits has 16 Charlieplexed LEDs
           connected to digital pins 5, 6, 7, 8, and 9.  You can read more about
           the board at http://tiny-circuits.com/learn/tinyduinoled/.
================================================================================
  $LastChangedDate: 2013-07-14 23:04:16 +0000 (Sun, 14 Jul 2013) $
  $LastChangedBy: maddy314@gmail.com $
================================================================================
  Copyright (c) 2013 Madeline Usher <maddy314 ~@~ gmail.com>
  
  The TinyDuino LED Shield Library is free software: you can redistribute it
  and/or modify it under the terms of the GNU General Public License as
  published by the Free Software Foundation, either version 3 of the License, 
  or (at your option) any later version.

  This library is distributed in the hope that it will be useful, but WITHOUT 
  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 
  FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.

  You should have received a copy of the GNU General Public License along with 
  this library.  If not, see <http://www.gnu.org/licenses/>.
================================================================================
*/

/*
================================================================================
Design Notes:

 The TinyDuino LED Shield uses digital pins 5 - 9 to control sixteen
 charlieplexed LEDs.  TinyCircuits has a tutorial discussing this board at
 http://tiny-circuits.com/learn/tinyduinoled/ .  For practical purposes, only 
 one LED can be on at a time in a charlieplexed array.  (There are exceptions --
 a large enough array could allow weird combinations of lines to cause multiple
 LEDs to be on at a time, but this library is not going to cover those cases.)
 So, to allow it to appear as if multiple LEDs are on at a time, this library 
 uses Timer 2 on the microcontroller to rapidly switch between LEDs.  
 
 The library sets up the timer with a frequency of approximately 800 Hz, so if
 all 16 LEDs are "on", the entire array will be refreshed with a frequency of
 about 50 Hz.  That seemed a good compromise that allowed the 8MHz TinyDuino to
 perform other tasks than just handling the LED refresh interrupts.  If your
 project is more CPU intensive, you might need an even slower refresh rate.  
 This is set in the function initTimerInterrupt().

Setup:

 (1) Add the entire tinyduino_ledboard folder to your Arduino libraries folder.
 (2) #include "tinyduino_ledboard.h" in your sketch.
 
Usage:

 Somewhere early in your sketch's execution (like in your setup() function), 
 call initTinyDuinoLEDBoard().
 
 Call setLED(<led_num>, <HIGH|LOW>) to turn an LED on or off.  The LEDs are 
 numbered from 0 through 15 in a clockwise order starting from the lower-left if
 the shield connector is at the bottom and you are looking at the board from 
 the top.
 
 allLEDsOff() and allLEDsOn() can be used to set all sixteen LEDs in one call.
 
 The above functions merely change a value in an array that is used by the timer
 interrupt to refresh the LEDs.  So until the next timer interrupt occurs, the
 state of the LEDs won't actually change.  As discussed above, the timer 
 interrupt is running at approximately 800 Hz, so it doesn't take very long 
 before the change is seen (less time than the human eye can ascertain. However,
 there are situations where you really need to guarantee that all the LEDs are 
 turned off before continuing in your program.  This arises, for example, if 
 you're about to put the microcontroller to sleep.  If it goes to sleep during
 a part of the refresh cycle where an LED is turned on, the associated output
 pins can be left active, and an LED will remain on for the entire time the
 system is supposed to be asleep.  In such cases, call clearLEDpins() after 
 calling allLEDsOff().  That will force all the LED control pins into an
 inactive state (sets them all to INPUT mode, which is a high impedance state
 that turns the LEDs off).

================================================================================
*/

#ifndef TINY_LEDBOARD_h
#define TINY_LEDBOARD_h

#include "Arduino.h"
#include <inttypes.h>


////////////////////////////////////////////////////////////////////////////////
/// Various Definitions

#define LEDBOARD_NUM_PINS   5
#define LEDBOARD_NUM_LEDS  16

typedef struct _LEDdesc
 {
  byte vcc;
  byte gnd;
 } LEDdesc;


////////////////////////////////////////////////////////////////////////////////
/// External functions

void initTinyDuinoLEDBoard ();
void setLED (int iLED, bool state);
void allLEDsOff ();
void allLEDsOn ();

void clearLEDpins ();


#endif  // TINY_LEDBOARD_h

////////////////////////////////////////////////////////////////////////////////
/// End of Code
